<?xml version='1.0'?><!DOCTYPE html PUBLIC><html xmlns='http://www.w3.org/1999/xhtml'>
  <head>
    <title>jMock - Custom Stubs</title>
    <link href='/jmock.css' title='Navigation View' rel='stylesheet' type='text/css' media='screen' />
    <link href='/print.css' title='Print Preview' rel='alternate stylesheet' type='text/css' media='screen' />
    <link href='/print.css' rel='stylesheet' type='text/css' media='print' />
    <meta content='' http-equiv='Content-Type' />
  </head>

  <body>
    <div id='banner'>
      <a href='/index.html'><img src='/logo.gif' id='logo' alt='jMock' /></a>
    </div>

    

    
      <div class='Content2Column' id='center'>
        <div id='content'>
          <h1 class='FirstChild'>Custom Stubs in jMock</h1><h2>or <i>Unusual Behaviour Deserves to be Mocked</i></h2><p>A mock object does two things: it tests that it receives the expected
method invocations and it stubs the behaviour of those methods. Almost all
methods can be stubbed in one of three basic ways: return nothing (a void
method), return a result to the caller or throw an exception. Sometimes,
however, you need to stub side effects of a method, such as a method that
calls back to the caller through an object reference passed as one of its
parameters. Luckily, jMock makes it easy to write custom stubs for methods
with strange behaviours and keep your tests easy to read when you do so.</p><p>Here's a simple example: we want to test a <code>NameCollector</code>
object that collects the names of a collection <code>Named</code> objects. It
will do so by passing a <code>List</code> to the <code>collectName</code>
method of the named objects. The named objects implement
<code>collectName</code> by addding their name to the list they receive. The
<code>Named</code> interface is shown below:</p><div class='Source Java'>
<pre>public interface Named {
    void collectName( List list );
}</pre>
</div><p>To test the behaviour of our object we will need to mock the
<code>Named</code> interface, and in particular we need to stub the <em>side
effect</em> of the <code>collectName</code> method. jMock provides stubs for
returning values and throwing exceptions but we will have to write our own
class to stub the side effect of the <code>Named</code> objects.</p><p>To write a stub:</p><ol>
  <li><p>Write a class that implements the <code><a href='/docs/javadoc/org/jmock/core/Stub.html'>Stub</a><span class='LinkFootnoteRef'><sup>1</sup></span></code> interface.
    Here's a stub that adds an element to a List received as the first
    argument of the method.</p>

    <div class='Source Java'>
    <pre>public class AddToListStub implements Stub
{
    Object element;

    public AddToListStub( Object element ) {
        this.element = element;
    }

    public StringBuffer describeTo( StringBuffer buffer ) {
        return buffer.append("adds &lt;"+element+"&gt; to a list");
    }

    public Object invoke( Invocation invocation ) throws Throwable {
        ((List)invocation.parameterValues.get(0)).add(element);
        return null;
    }
}</pre>
    </div>
  </li>
  <li><p>Write a factory method in your tests class that instantiates your
    new stub class.</p>

    <div class='Source Java'>
    <pre>private Stub addListElement( Object newElement ) {
    return new AddToListStub(newElement);
}</pre>
    </div>
  </li>
  <li><p>Call your factory method within the actual parameter list of the
    mock's <code>will</code> method.</p>

    <div class='Source Java'>
    <pre>Mock mockNamed = mock(Named.class);
String name = "name";

mockNamed.expects(once()).method("collectName").with(NOT_NULL)
    .will(addListElement(name));</pre>
    </div>
  </li>
</ol>
        <div class='LinkFootnotes'><p class='LinkFootnotesHeader'>Links:</p><p>1. <a href='http://www.jmock.org/docs/javadoc/org/jmock/core/Stub.html'>http://www.jmock.org/docs/javadoc/org/jmock/core/Stub.html</a></p></div></div>
	    <div class='Meta'>
	      <p><a href='http://cvs.jmock.codehaus.org/jmock/website/content/custom-stubs.html'>Document History</a></p>
	    </div>
      </div>
    

    <div class='SidePanel' id='left'>
      <div class='MenuGroup'>
        <h1><a href='/download.html'>Software</a></h1>
        <ul>
          <li><a href='/download.html'>Download</a></li>
          <li><a href='/repository.html'>Anonymous CVS Access</a></li>
          <li><a href='/license.html'>Project License</a></li>
          <li><a href='/CHANGELOG'>Change Log</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/docs.html'>Documentation...</a></h1>
        <ul>
          <li><a href='/getting-started.html'>Getting Started</a></li>
          <!-- <li><a href="">Frequently Asked Questions</a></li> -->
          <li><a href='/docs/javadoc/index.html' target='jmock-javadoc'>JavaDocs</a></li>
          <li><a href='http://www.mockobjects.com'>More about Mock Objects</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>User Support</h1>
        <ul>
          <li><a href='/mailing-lists.html'>Mailing Lists</a></li>
          <li><a href='http://jira.codehaus.org/secure/BrowseProject.jspa?id=10336'>Issue Tracker</a></li>
          <li><a href='/news-rss2.xml'>News Feed (RSS 2.0)</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/development.html'>Development...</a></h1>
        <ul>
          <li><a href='/how-to-contribute.html'>How to Contribute</a></li>
          <li><a href='/team.html'>Development Team</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>Related Sites</h1>
        <ul>
          <li><a href='http://www.mockobjects.com'>Mock Objects</a></li>
          <li><a href='http://www.junit.org'>JUnit</a></li>
          <li><a href='http://www.nmock.org'>nMock</a></li>
          <li><a href='http://www.codehaus.org'>Project hosted by Codehaus</a></li>
        </ul>
      </div>
    </div>

    
  </body>
</html>